home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / game / misc / Quest.lha / Quest / doc / qsrcinfo.txt next >
Text File  |  1999-01-28  |  12KB  |  331 lines
  1. Quest Source Code v1.1
  2.  by Trey Harrison (otaku@u.washington.edu)
  3. and Chris Carollo (carollo@cis.ohio-state.edu)
  4. Release Notes
  5. November 23rd, 1996
  6. ----------------------
  7.  
  8. -------
  9. Welcome
  10. -------
  11.         HI! And Welcome to the Quest Source Code (v1.1) Release Notes!
  12. I've done the best I could arranging the modules, and including information
  13. below that hopefully explains the basics of how Quest works. There is some
  14. legal information you definitely need to know about, find it in legal.txt.
  15. Read it, learn it, love it, obey it. We dont want people ripping off our
  16. 5 months of work. All of the C and H files will compile into one nice
  17. 32-bit DOS4GW executable (just run wmake), assuming you have all your
  18. environment variables for Watcom set correctly. And if you arent using watcom,
  19. well, I wish you the best of luck. The one .pas file will compile with Turbo
  20. Pascal 7.0 (or probably any old version of pascal, but just to be on the safe
  21. side, I thought I'd let you know what I used to compile it 6 months ago when
  22. it was written). Even if you dont have Pascal, it doesnt matter, because I've
  23. included the executable that does the menu.txt -> menu.dat conversion.
  24. The format of the menu.txt file should be self explanatory. The "mappings"
  25. of the function ID's seen in the menu.txt file can be found in the menu_exe()
  26. function in the menu.c module.
  27.  
  28. -----------------------------------
  29. The Official Quest Seal of Approval
  30. -----------------------------------
  31.         We can't have 5 different "new" version of Quest floating around.
  32. Similarly, we can't have 5 different versions of a Win95 Quest port flying
  33. around. So, before you release your port or your new version, you must
  34. have the OK from Chris Carollo and Trey Harrison. It is unlikely that we
  35. will allow more than 1 version of Quest per platform. So if you are seriously
  36. trying to port it, I suggest letting us know about it and sending us a working
  37. demo as soon as possible. Otherwise we'll be sure to put your name on our
  38. page under the category of "People who released a Quest derivitive work
  39. without our Seal of Approval". And if you sell it, well then we'll definitely
  40. be doing a bit more than putting your name on a blacklist. Read legal.txt for
  41. more information.
  42.  
  43. --------------------------------
  44. Here is the flow of the program:
  45. --------------------------------
  46.  
  47.     1) Init Everything:
  48.         a. Init list variables to NULL, strings to \0, etc
  49.         b. Read the config file (quest.cfg)
  50.         c. Read the mdl info file (mdlref.lst)
  51.         d. Load a map from the command line if specified
  52.            or create a new one (and then init the camera
  53.            positions)
  54.         e. Init the video mode (set up screen buffer also)
  55.         f. Init the mouse
  56.         g. Init the "display" (load bitmap graphics, palette,
  57.            etc)
  58.         h. Load the menu data file and init the menu system
  59.         i. Init the Tool Buttons
  60.         j. Init the keyboard handler
  61.         k. Update all of the viewports
  62.         l. Copy the screen buffer to video memory
  63.         m. Draw the mouse
  64.  
  65.     2) The Main Loop:
  66.         {
  67.         if the exit flag is set, then exit        
  68.     
  69.         Find the mouse. Depending on what section of the
  70.         screen its in, call an appropriate handler.
  71.         
  72.         Update the mouse position.
  73.         Process any key presses.
  74.         }
  75.  
  76.     3) Exit the program:        
  77.         a. Save the configuration file
  78.         b. Shut off the keyboard handler
  79.  
  80. ---------------------------------------------------------------
  81. Here is an explanation of some of the more important functions:
  82. ---------------------------------------------------------------
  83.  
  84. FindMouse(), mouse.c
  85. --------------------
  86.     Determines which "window" the mouse is over. There are 5
  87. windows: Status window, menu window, tool window, message window, and
  88. map window.
  89.  
  90. UpdateMap(), display.c
  91. ----------------------
  92.     Called from the main loop. Depending on what mode Quest is in
  93. and whether or not the mouse is just sitting there or if it has been
  94. clicked in the active viewport or in an unactive viewport, call 
  95. appropriate an appropriate handler or activate a viewport / deactivate
  96. another, etc.
  97.  
  98. UpdateMenu(), menu.c
  99. --------------------
  100.     Called from the main loop. Highlights the menu entry the mouse
  101. is over, checks for a click. If there is a mouse click, calls Menu_Exe
  102. which determines (by the menu id numbers) what to do from there. More
  103. menu information can be garnered from menu.txt and menucnv.pas.
  104.  
  105. UpdateMsg(), message.c
  106. ----------------------
  107.     Called from the main loop. Just scrolls the message window if
  108. necessary.
  109.  
  110. UpdateTool(), tool.c
  111. --------------------
  112.     Called from the main loop. Checks to see if any tool buttons
  113. have been clicked and takes appropriate actions.
  114.  
  115. UpdateViewport() / UpdateAllViewports(), 3d.c
  116. ---------------------------------------------
  117.     Called from all throughout the program whenever the screen
  118. needs to be "rendered". These functions, along with DrawViewport() and
  119. DrawBSPTree() are the core map drawing functions. UpdateViewport()
  120. is what you would call to update a specific viewport (note that there
  121. are a max of 3 viewports, all of which are in the map window).
  122. UpdateAllViewports() is what you would call to update all of the
  123. currently visible viewports.
  124.  
  125. RefreshPart() / RefreshScreen(), video.c
  126. ----------------------------------------
  127.     This does the copying from the screen buffer to video memory.
  128. Very few things are written directly to video memory (the mouse is
  129. all that comes to mind at the moment). RefreshPart will copy
  130. any rectangular portion of the screen buffer, RefreshScreen() will
  131. copy the entire screen buffer.
  132.  
  133. UpdateMouse(), mouse.c
  134. ----------------------
  135.     Updates the mouse's position and also takes a screenshot if
  136. applicable. Hows that for poor design. UpdateMouse() is called more
  137. than any other function. Demo recording used to go through it. Anyway
  138. it calls a DOS interrupt to get the mouse's position, erases the
  139. old mouse, draws the new position, stores the previous position and
  140. new position in the global mouse variable (aptly named "mouse"). So
  141. anytime you want the mouse's coordinates as of the last UpdateMouse,
  142. mouse.x and mouse.y are what you want.
  143.  
  144. GetMousePos(), mouse.c
  145. ----------------------
  146.     Use this if you want to update the mouse variable without
  147. drawing the new mouse position to the screen. Examining the code
  148. will show you that GetMousePos() is actually called by UpdateMouse().
  149.  
  150. TestKey(), keyboard.c
  151. ---------------------
  152.     Call this with the scancode of the key you want to check.
  153. It will return TRUE if its pressed, FALSE if it isnt.
  154.  
  155. Q_free(), Q_malloc(), Q_realloc(), memory.c
  156. -------------------------------------------
  157.     These functions handle all memory allocation / reallocation /
  158. freeing. They work exactly like their standard C counterparts (malloc,
  159. free, realloc). They also update the memused variable (useful in 
  160. tracking down memory leaks / bugs).
  161.  
  162. ---------------------------------------------
  163. Here is an explanation of some of the modules
  164. ---------------------------------------------
  165.  
  166. 3D.C:    
  167.     Handles most of the 3D matrix and drawing operations. The core
  168.     3D and 2D line-rendering module.
  169.  
  170. POLY.C:
  171.     Handles the Z-buffered polygon drawing stuff.
  172.  
  173. BSP.C:
  174.     Handles everything having to do with BSP stuff. Calls very
  175.     few functions outside of its own. Building the tree, clipping
  176.     faces,traversing the tree, rasterizing and drawing the faces 
  177.     is all done in it.
  178.  
  179. CAMERA.C:
  180.     Handles camera movement (looking up, down, left, right, moving,
  181.     etc).
  182.  
  183. CONFIG.C:
  184.     Reads and Writes from the Quest.Cfg file. Also has a function
  185.     LoadSetup() that reads the Quest setup from a .map file.
  186.  
  187. DISPLAY.C:
  188.     Handles bitmap loading, registering, finding, drawing. Handles 
  189.     the map window too, for some reason.
  190.  
  191. EDBRUSH.C:
  192.     Handles brush and brush vertex editing. Moving brushes, 
  193.     copying brushes, selecting brushes, selecting brush vertices, 
  194.     checking the convexivity of a brush, making new brushes, 
  195.     scaling and rotating, etc.
  196.  
  197. EDENT.C,EDFACE.C,EDSCRIPT.C:
  198.     Do basically the same thing as edbrush.c for entities,
  199.     faces, and scripts.
  200.  
  201. ENTITY.C:
  202.     Handles entity initialization, setting key/value pairs, etc.
  203.  
  204. ERROR.C:
  205.     Has the HandleError() function. thats pretty much it.
  206.  
  207. GEOM.C:
  208.     Has the geometric functions that every good boy should know
  209.     and love (Normalize a vector, Crossproduct 2 vectors, dot
  210.     product 2 vectors, get the sign of a number, etc).
  211.  
  212. NEWGROUP.C:
  213.     Handles group manipulations (creating the world group, creating
  214.     user specified groups, the group picker window, the group
  215.     popup window, removing groups, loading group info from a file,
  216.     etc). Actual Group Loading and Saving is done in MAP.C.
  217.  
  218. KEYBOARD.C:
  219.     Has the keyboard handler and the TestKey function.
  220.  
  221. MAP.C:
  222.         Handles all map loading and saving. Also handles group loading
  223.     and saving. Uses a lot of CSG routines from clip.c during the
  224.     map loading process.
  225.  
  226. MDL.C:
  227.     Handles all mdl loading / drawing.
  228.  
  229. MENU.C:
  230.     Handles all menu functions. Drawing the menu, highlighting 
  231.     different parts of the menu, calling menu functions, etc.
  232.  
  233. MESSAGE.C:
  234.     Handles message scrolling, displaying, dumping, etc.
  235.  
  236. MOUSE.C:
  237.     Handles all mouse operations. Init, Drawing, "Un"drawing,
  238.     updating the position, determining which window on the screen
  239.     it is in. Also handles taking screenshots, also handles
  240.     demo playback and recording (which may or may not still work).
  241.  
  242. QUI.C:
  243.     Handles all aspects of the user interface except for most of
  244.     the popup windows (those are in POPUPWIN.C and TEMPPOP.C).
  245.     Handles drawing buttons, making buttons out of
  246.     text, drawing strings, drawing characters, loading / registering
  247.     fonts, redrawing any of the 5 "windows" (status, menu, message,
  248.     tool, map)
  249.  
  250. STATUS.C:
  251.     Updates the status window, also sets preferences from within
  252.     Quest.
  253.  
  254. TOOL.C:
  255.     Updates the tool window.
  256.  
  257. VIDEO.C:
  258.     Contains many video operations. The only ones called frequently
  259.     are RefreshScreen,RefreshPart, and the line drawing primitives.
  260.  
  261. VBE.C:
  262.     Contains VBE 1.2 interface routines. This is based heavily
  263.     upon code by Bob Pendleton. He has a fantastic page at
  264.     http://www.pendleton.com/rants.html.
  265.  
  266. FILE.C:
  267.     Contains WAD interface functions. Reading textures from wads,
  268.     primarily. Also gets directory and file lists, also has
  269.     functions to read strings of input from the keyboard. Dont
  270.     ask why its in file.c =).
  271.  
  272. POPUPWIN.C,TEMPPOP.C:
  273.     Has all file popup windows, also texture selection popup window,
  274.     also has the entity popup window.
  275.  
  276. MEMORY.C:
  277.     Has the old and new memory scheme. The "new" memory scheme
  278.     likely does not work. Either will do your basic malloc,
  279.     realloc, and free.
  280.  
  281. CLIP.C:
  282.     Has the somewhat complex CSG operations: face splitting,
  283.     brush building, brush intersection (AddBrushes()), brush
  284.     subtraction (SubtractBrushes()).
  285.  
  286. --------------------
  287. Info on the .h files
  288. --------------------
  289.  
  290. DEFINES.H:
  291.     Contains all #defines (well, most of them). Keys, window names,
  292.     a few macro functions.
  293.  
  294. PROCS.H:
  295.     Contains almost all of the function prototypes. This is a
  296.     pretty lame way of doing things, but oh well.
  297.  
  298. TYPES.H:
  299.     Contains all type definitions except for mdl types (which can
  300.     be found in mdl.h).
  301.  
  302. GLOBALS.H:
  303.     Contains *references* to global variables. Most of the globals
  304.     are instantiated in quest.c, and refered to in globals.h
  305.     ie in quest.c, you might find:
  306.         char mapfilename[128];
  307.     and in globals.h:
  308.         extern char mapfilename[128];
  309.     This is basically to provide easy access to all the often
  310.     used variables in the program without having to keep passing
  311.     them around as function arguments.
  312.     
  313.     
  314.  
  315. Final Comments
  316. --------------
  317.     If you were to port Quest, there are only a few things you
  318. need to worry about: rewriting the UpdateMouse and GetMousePos
  319. functions so that they actually work on whatever platform you are
  320. compiling for. Rewrite the RefreshScreen and RefreshPart functions
  321. so that they actually draw from the virtual screen buffer to the
  322. screen. Rewrite TestKey() and the keyboard interrupt so that they
  323. actually work on your platform. Find the very few spots where we
  324. used assembler and, well, do something about it :)
  325.                            
  326. Its been real, its been fun, its even been real fun. Look for our names
  327. in future big coding projects!
  328.  
  329.        Chris Carollo         and        Trey Harrison
  330. carollo@cis.ohio-state.edu         otaku@u.washington.edu
  331.